<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2016 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Funding Free Software", the Front-Cover
Texts being (a) (see below), and with the Back-Cover Texts being (b)
(see below).  A copy of the license is included in the section entitled
"GNU Free Documentation License".

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
     software.  Copies published by the Free Software Foundation raise
     funds for GNU development. -->
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNU Compiler Collection (GCC): Instrumentation Options</title>

<meta name="description" content="Using the GNU Compiler Collection (GCC): Instrumentation Options">
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Instrumentation Options">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Invoking-GCC.html#Invoking-GCC" rel="up" title="Invoking GCC">
<link href="Preprocessor-Options.html#Preprocessor-Options" rel="next" title="Preprocessor Options">
<link href="Optimize-Options.html#Optimize-Options" rel="prev" title="Optimize Options">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Instrumentation-Options"></a>
<div class="header">
<p>
Next: <a href="Preprocessor-Options.html#Preprocessor-Options" accesskey="n" rel="next">Preprocessor Options</a>, Previous: <a href="Optimize-Options.html#Optimize-Options" accesskey="p" rel="prev">Optimize Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Program-Instrumentation-Options"></a>
<h3 class="section">3.11 Program Instrumentation Options</h3>
<a name="index-instrumentation-options"></a>
<a name="index-program-instrumentation-options"></a>
<a name="index-run_002dtime-error-checking-options"></a>
<a name="index-profiling-options"></a>
<a name="index-options_002c-program-instrumentation"></a>
<a name="index-options_002c-run_002dtime-error-checking"></a>
<a name="index-options_002c-profiling"></a>

<p>GCC supports a number of command-line options that control adding
run-time instrumentation to the code it normally generates.  
For example, one purpose of instrumentation is collect profiling
statistics for use in finding program hot spots, code coverage
analysis, or profile-guided optimizations.
Another class of program instrumentation is adding run-time checking 
to detect programming errors like invalid pointer
dereferences or out-of-bounds array accesses, as well as deliberately
hostile attacks such as stack smashing or C++ vtable hijacking.
There is also a general hook which can be used to implement other
forms of tracing or function-level instrumentation for debug or
program analysis purposes.
</p>
<dl compact="compact">
<dd><a name="index-prof"></a>
</dd>
<dt><code>-p</code></dt>
<dd><a name="index-p"></a>
<p>Generate extra code to write profile information suitable for the
analysis program <code>prof</code>.  You must use this option when compiling
the source files you want data about, and you must also use it when
linking.
</p>
<a name="index-gprof"></a>
</dd>
<dt><code>-pg</code></dt>
<dd><a name="index-pg"></a>
<p>Generate extra code to write profile information suitable for the
analysis program <code>gprof</code>.  You must use this option when compiling
the source files you want data about, and you must also use it when
linking.
</p>
</dd>
<dt><code>-fprofile-arcs</code></dt>
<dd><a name="index-fprofile_002darcs"></a>
<p>Add code so that program flow <em>arcs</em> are instrumented.  During
execution the program records how many times each branch and call is
executed and how many times it is taken or returns.  When the compiled
program exits it saves this data to a file called
<samp><var>auxname</var>.gcda</samp> for each source file.  The data may be used for
profile-directed optimizations (<samp>-fbranch-probabilities</samp>), or for
test coverage analysis (<samp>-ftest-coverage</samp>).  Each object file&rsquo;s
<var>auxname</var> is generated from the name of the output file, if
explicitly specified and it is not the final executable, otherwise it is
the basename of the source file.  In both cases any suffix is removed
(e.g. <samp>foo.gcda</samp> for input file <samp>dir/foo.c</samp>, or
<samp>dir/foo.gcda</samp> for output file specified as <samp>-o dir/foo.o</samp>).
See <a href="Cross_002dprofiling.html#Cross_002dprofiling">Cross-profiling</a>.
</p>
<a name="index-gcov"></a>
</dd>
<dt><code>--coverage</code></dt>
<dd><a name="index-coverage"></a>

<p>This option is used to compile and link code instrumented for coverage
analysis.  The option is a synonym for <samp>-fprofile-arcs</samp>
<samp>-ftest-coverage</samp> (when compiling) and <samp>-lgcov</samp> (when
linking).  See the documentation for those options for more details.
</p>
<ul>
<li> Compile the source files with <samp>-fprofile-arcs</samp> plus optimization
and code generation options.  For test coverage analysis, use the
additional <samp>-ftest-coverage</samp> option.  You do not need to profile
every source file in a program.

</li><li> Link your object files with <samp>-lgcov</samp> or <samp>-fprofile-arcs</samp>
(the latter implies the former).

</li><li> Run the program on a representative workload to generate the arc profile
information.  This may be repeated any number of times.  You can run
concurrent instances of your program, and provided that the file system
supports locking, the data files will be correctly updated.  Also
<code>fork</code> calls are detected and correctly handled (double counting
will not happen).

</li><li> For profile-directed optimizations, compile the source files again with
the same optimization and code generation options plus
<samp>-fbranch-probabilities</samp> (see <a href="Optimize-Options.html#Optimize-Options">Options that
Control Optimization</a>).

</li><li> For test coverage analysis, use <code>gcov</code> to produce human readable
information from the <samp>.gcno</samp> and <samp>.gcda</samp> files.  Refer to the
<code>gcov</code> documentation for further information.

</li></ul>

<p>With <samp>-fprofile-arcs</samp>, for each function of your program GCC
creates a program flow graph, then finds a spanning tree for the graph.
Only arcs that are not on the spanning tree have to be instrumented: the
compiler adds code to count the number of times that these arcs are
executed.  When an arc is the only exit or only entrance to a block, the
instrumentation code can be added to the block; otherwise, a new basic
block must be created to hold the instrumentation code.
</p>
</dd>
<dt><code>-ftest-coverage</code></dt>
<dd><a name="index-ftest_002dcoverage"></a>
<p>Produce a notes file that the <code>gcov</code> code-coverage utility
(see <a href="Gcov.html#Gcov"><code>gcov</code>&mdash;a Test Coverage Program</a>) can use to
show program coverage.  Each source file&rsquo;s note file is called
<samp><var>auxname</var>.gcno</samp>.  Refer to the <samp>-fprofile-arcs</samp> option
above for a description of <var>auxname</var> and instructions on how to
generate test coverage data.  Coverage data matches the source files
more closely if you do not optimize.
</p>
</dd>
<dt><code>-fprofile-dir=<var>path</var></code></dt>
<dd><a name="index-fprofile_002ddir"></a>

<p>Set the directory to search for the profile data files in to <var>path</var>.
This option affects only the profile data generated by
<samp>-fprofile-generate</samp>, <samp>-ftest-coverage</samp>, <samp>-fprofile-arcs</samp>
and used by <samp>-fprofile-use</samp> and <samp>-fbranch-probabilities</samp>
and its related options.  Both absolute and relative paths can be used.
By default, GCC uses the current directory as <var>path</var>, thus the
profile data file appears in the same directory as the object file.
</p>
</dd>
<dt><code>-fprofile-generate</code></dt>
<dt><code>-fprofile-generate=<var>path</var></code></dt>
<dd><a name="index-fprofile_002dgenerate"></a>

<p>Enable options usually used for instrumenting application to produce
profile useful for later recompilation with profile feedback based
optimization.  You must use <samp>-fprofile-generate</samp> both when
compiling and when linking your program.
</p>
<p>The following options are enabled: <samp>-fprofile-arcs</samp>, <samp>-fprofile-values</samp>, <samp>-fvpt</samp>.
</p>
<p>If <var>path</var> is specified, GCC looks at the <var>path</var> to find
the profile feedback data files. See <samp>-fprofile-dir</samp>.
</p>
<p>To optimize the program based on the collected profile information, use
<samp>-fprofile-use</samp>.  See <a href="Optimize-Options.html#Optimize-Options">Optimize Options</a>, for more information.
</p>
</dd>
<dt><code>-fsanitize=address</code></dt>
<dd><a name="index-fsanitize_003daddress"></a>
<p>Enable AddressSanitizer, a fast memory error detector.
Memory access instructions are instrumented to detect
out-of-bounds and use-after-free bugs.
See <a href="https://github.com/google/sanitizers/wiki/AddressSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizer</a> for
more details.  The run-time behavior can be influenced using the
<code>ASAN_OPTIONS</code> environment variable.  When set to <code>help=1</code>,
the available options are shown at startup of the instrumented program.  See
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags">https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags</a>
for a list of supported options.
</p>
</dd>
<dt><code>-fsanitize=kernel-address</code></dt>
<dd><a name="index-fsanitize_003dkernel_002daddress"></a>
<p>Enable AddressSanitizer for Linux kernel.
See <a href="https://github.com/google/kasan/wiki">https://github.com/google/kasan/wiki</a> for more details.
</p>
</dd>
<dt><code>-fsanitize=thread</code></dt>
<dd><a name="index-fsanitize_003dthread"></a>
<p>Enable ThreadSanitizer, a fast data race detector.
Memory access instructions are instrumented to detect
data race bugs.  See <a href="https://github.com/google/sanitizers/wiki#threadsanitizer">https://github.com/google/sanitizers/wiki#threadsanitizer</a> for more
details. The run-time behavior can be influenced using the <code>TSAN_OPTIONS</code>
environment variable; see
<a href="https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags">https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags</a> for a list of
supported options.
</p>
</dd>
<dt><code>-fsanitize=leak</code></dt>
<dd><a name="index-fsanitize_003dleak"></a>
<p>Enable LeakSanitizer, a memory leak detector.
This option only matters for linking of executables and if neither
<samp>-fsanitize=address</samp> nor <samp>-fsanitize=thread</samp> is used.  In that
case the executable is linked against a library that overrides <code>malloc</code>
and other allocator functions.  See
<a href="https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer">https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer</a> for more
details.  The run-time behavior can be influenced using the
<code>LSAN_OPTIONS</code> environment variable.
</p>
</dd>
<dt><code>-fsanitize=undefined</code></dt>
<dd><a name="index-fsanitize_003dundefined"></a>
<p>Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector.
Various computations are instrumented to detect undefined behavior
at runtime.  Current suboptions are:
</p>
<dl compact="compact">
<dt><code>-fsanitize=shift</code></dt>
<dd><a name="index-fsanitize_003dshift"></a>
<p>This option enables checking that the result of a shift operation is
not undefined.  Note that what exactly is considered undefined differs
slightly between C and C++, as well as between ISO C90 and C99, etc.
</p>
</dd>
<dt><code>-fsanitize=integer-divide-by-zero</code></dt>
<dd><a name="index-fsanitize_003dinteger_002ddivide_002dby_002dzero"></a>
<p>Detect integer division by zero as well as <code>INT_MIN / -1</code> division.
</p>
</dd>
<dt><code>-fsanitize=unreachable</code></dt>
<dd><a name="index-fsanitize_003dunreachable"></a>
<p>With this option, the compiler turns the <code>__builtin_unreachable</code>
call into a diagnostics message call instead.  When reaching the
<code>__builtin_unreachable</code> call, the behavior is undefined.
</p>
</dd>
<dt><code>-fsanitize=vla-bound</code></dt>
<dd><a name="index-fsanitize_003dvla_002dbound"></a>
<p>This option instructs the compiler to check that the size of a variable
length array is positive.
</p>
</dd>
<dt><code>-fsanitize=null</code></dt>
<dd><a name="index-fsanitize_003dnull"></a>
<p>This option enables pointer checking.  Particularly, the application
built with this option turned on will issue an error message when it
tries to dereference a NULL pointer, or if a reference (possibly an
rvalue reference) is bound to a NULL pointer, or if a method is invoked
on an object pointed by a NULL pointer.
</p>
</dd>
<dt><code>-fsanitize=return</code></dt>
<dd><a name="index-fsanitize_003dreturn"></a>
<p>This option enables return statement checking.  Programs
built with this option turned on will issue an error message
when the end of a non-void function is reached without actually
returning a value.  This option works in C++ only.
</p>
</dd>
<dt><code>-fsanitize=signed-integer-overflow</code></dt>
<dd><a name="index-fsanitize_003dsigned_002dinteger_002doverflow"></a>
<p>This option enables signed integer overflow checking.  We check that
the result of <code>+</code>, <code>*</code>, and both unary and binary <code>-</code>
does not overflow in the signed arithmetics.  Note, integer promotion
rules must be taken into account.  That is, the following is not an
overflow:
</p><div class="smallexample">
<pre class="smallexample">signed char a = SCHAR_MAX;
a++;
</pre></div>

</dd>
<dt><code>-fsanitize=bounds</code></dt>
<dd><a name="index-fsanitize_003dbounds"></a>
<p>This option enables instrumentation of array bounds.  Various out of bounds
accesses are detected.  Flexible array members, flexible array member-like
arrays, and initializers of variables with static storage are not instrumented.
</p>
</dd>
<dt><code>-fsanitize=bounds-strict</code></dt>
<dd><a name="index-fsanitize_003dbounds_002dstrict"></a>
<p>This option enables strict instrumentation of array bounds.  Most out of bounds
accesses are detected, including flexible array members and flexible array
member-like arrays.  Initializers of variables with static storage are not
instrumented.
</p>
</dd>
<dt><code>-fsanitize=alignment</code></dt>
<dd><a name="index-fsanitize_003dalignment"></a>

<p>This option enables checking of alignment of pointers when they are
dereferenced, or when a reference is bound to insufficiently aligned target,
or when a method or constructor is invoked on insufficiently aligned object.
</p>
</dd>
<dt><code>-fsanitize=object-size</code></dt>
<dd><a name="index-fsanitize_003dobject_002dsize"></a>
<p>This option enables instrumentation of memory references using the
<code>__builtin_object_size</code> function.  Various out of bounds pointer
accesses are detected.
</p>
</dd>
<dt><code>-fsanitize=float-divide-by-zero</code></dt>
<dd><a name="index-fsanitize_003dfloat_002ddivide_002dby_002dzero"></a>
<p>Detect floating-point division by zero.  Unlike other similar options,
<samp>-fsanitize=float-divide-by-zero</samp> is not enabled by
<samp>-fsanitize=undefined</samp>, since floating-point division by zero can
be a legitimate way of obtaining infinities and NaNs.
</p>
</dd>
<dt><code>-fsanitize=float-cast-overflow</code></dt>
<dd><a name="index-fsanitize_003dfloat_002dcast_002doverflow"></a>
<p>This option enables floating-point type to integer conversion checking.
We check that the result of the conversion does not overflow.
Unlike other similar options, <samp>-fsanitize=float-cast-overflow</samp> is
not enabled by <samp>-fsanitize=undefined</samp>.
This option does not work well with <code>FE_INVALID</code> exceptions enabled.
</p>
</dd>
<dt><code>-fsanitize=nonnull-attribute</code></dt>
<dd><a name="index-fsanitize_003dnonnull_002dattribute"></a>

<p>This option enables instrumentation of calls, checking whether null values
are not passed to arguments marked as requiring a non-null value by the
<code>nonnull</code> function attribute.
</p>
</dd>
<dt><code>-fsanitize=returns-nonnull-attribute</code></dt>
<dd><a name="index-fsanitize_003dreturns_002dnonnull_002dattribute"></a>

<p>This option enables instrumentation of return statements in functions
marked with <code>returns_nonnull</code> function attribute, to detect returning
of null values from such functions.
</p>
</dd>
<dt><code>-fsanitize=bool</code></dt>
<dd><a name="index-fsanitize_003dbool"></a>

<p>This option enables instrumentation of loads from bool.  If a value other
than 0/1 is loaded, a run-time error is issued.
</p>
</dd>
<dt><code>-fsanitize=enum</code></dt>
<dd><a name="index-fsanitize_003denum"></a>

<p>This option enables instrumentation of loads from an enum type.  If
a value outside the range of values for the enum type is loaded,
a run-time error is issued.
</p>
</dd>
<dt><code>-fsanitize=vptr</code></dt>
<dd><a name="index-fsanitize_003dvptr"></a>

<p>This option enables instrumentation of C++ member function calls, member
accesses and some conversions between pointers to base and derived classes,
to verify the referenced object has the correct dynamic type.
</p>
</dd>
</dl>

<p>While <samp>-ftrapv</samp> causes traps for signed overflows to be emitted,
<samp>-fsanitize=undefined</samp> gives a diagnostic message.
This currently works only for the C family of languages.
</p>
</dd>
<dt><code>-fno-sanitize=all</code></dt>
<dd><a name="index-fno_002dsanitize_003dall"></a>

<p>This option disables all previously enabled sanitizers.
<samp>-fsanitize=all</samp> is not allowed, as some sanitizers cannot be used
together.
</p>
</dd>
<dt><code>-fasan-shadow-offset=<var>number</var></code></dt>
<dd><a name="index-fasan_002dshadow_002doffset"></a>
<p>This option forces GCC to use custom shadow offset in AddressSanitizer checks.
It is useful for experimenting with different shadow memory layouts in
Kernel AddressSanitizer.
</p>
</dd>
<dt><code>-fsanitize-sections=<var>s1</var>,<var>s2</var>,...</code></dt>
<dd><a name="index-fsanitize_002dsections"></a>
<p>Sanitize global variables in selected user-defined sections.  <var>si</var> may
contain wildcards.
</p>
</dd>
<dt><code>-fsanitize-recover<span class="roman">[</span>=<var>opts</var><span class="roman">]</span></code></dt>
<dd><a name="index-fsanitize_002drecover"></a>
<a name="index-fno_002dsanitize_002drecover"></a>
<p><samp>-fsanitize-recover=</samp> controls error recovery mode for sanitizers
mentioned in comma-separated list of <var>opts</var>.  Enabling this option
for a sanitizer component causes it to attempt to continue
running the program as if no error happened.  This means multiple
runtime errors can be reported in a single program run, and the exit
code of the program may indicate success even when errors
have been reported.  The <samp>-fno-sanitize-recover=</samp> option
can be used to alter
this behavior: only the first detected error is reported
and program then exits with a non-zero exit code.
</p>
<p>Currently this feature only works for <samp>-fsanitize=undefined</samp> (and its suboptions
except for <samp>-fsanitize=unreachable</samp> and <samp>-fsanitize=return</samp>),
<samp>-fsanitize=float-cast-overflow</samp>, <samp>-fsanitize=float-divide-by-zero</samp>,
<samp>-fsanitize=kernel-address</samp> and <samp>-fsanitize=address</samp>.
For these sanitizers error recovery is turned on by default, except <samp>-fsanitize=address</samp>,
for which this feature is experimental.
<samp>-fsanitize-recover=all</samp> and <samp>-fno-sanitize-recover=all</samp> is also
accepted, the former enables recovery for all sanitizers that support it,
the latter disables recovery for all sanitizers that support it.
</p>
<p>Syntax without explicit <var>opts</var> parameter is deprecated.  It is equivalent to
</p><div class="smallexample">
<pre class="smallexample">-fsanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
</pre></div>
<p>Similarly <samp>-fno-sanitize-recover</samp> is equivalent to
</p><div class="smallexample">
<pre class="smallexample">-fno-sanitize-recover=undefined,float-cast-overflow,float-divide-by-zero
</pre></div>

</dd>
<dt><code>-fsanitize-undefined-trap-on-error</code></dt>
<dd><a name="index-fsanitize_002dundefined_002dtrap_002don_002derror"></a>
<p>The <samp>-fsanitize-undefined-trap-on-error</samp> option instructs the compiler to
report undefined behavior using <code>__builtin_trap</code> rather than
a <code>libubsan</code> library routine.  The advantage of this is that the
<code>libubsan</code> library is not needed and is not linked in, so this
is usable even in freestanding environments.
</p>
</dd>
<dt><code>-fsanitize-coverage=trace-pc</code></dt>
<dd><a name="index-fsanitize_002dcoverage_003dtrace_002dpc"></a>
<p>Enable coverage-guided fuzzing code instrumentation.
Inserts a call to <code>__sanitizer_cov_trace_pc</code> into every basic block.
</p>
</dd>
<dt><code>-fbounds-check</code></dt>
<dd><a name="index-fbounds_002dcheck"></a>
<p>For front ends that support it, generate additional code to check that
indices used to access arrays are within the declared range.  This is
currently only supported by the Java and Fortran front ends, where
this option defaults to true and false respectively.
</p>
</dd>
<dt><code>-fcheck-pointer-bounds</code></dt>
<dd><a name="index-fcheck_002dpointer_002dbounds"></a>
<a name="index-fno_002dcheck_002dpointer_002dbounds"></a>
<a name="index-Pointer-Bounds-Checker-options"></a>
<p>Enable Pointer Bounds Checker instrumentation.  Each memory reference
is instrumented with checks of the pointer used for memory access against
bounds associated with that pointer.  
</p>
<p>Currently there
is only an implementation for Intel MPX available, thus x86 GNU/Linux target
and <samp>-mmpx</samp> are required to enable this feature.  
MPX-based instrumentation requires
a runtime library to enable MPX in hardware and handle bounds
violation signals.  By default when <samp>-fcheck-pointer-bounds</samp>
and <samp>-mmpx</samp> options are used to link a program, the GCC driver
links against the <samp>libmpx</samp> and <samp>libmpxwrappers</samp> libraries.
Bounds checking on calls to dynamic libraries requires a linker
with <samp>-z bndplt</samp> support; if GCC was configured with a linker
without support for this option (including the Gold linker and older
versions of ld), a warning is given if you link with <samp>-mmpx</samp>
without also specifying <samp>-static</samp>, since the overall effectiveness
of the bounds checking protection is reduced.
See also <samp>-static-libmpxwrappers</samp>.
</p>
<p>MPX-based instrumentation
may be used for debugging and also may be included in production code
to increase program security.  Depending on usage, you may
have different requirements for the runtime library.  The current version
of the MPX runtime library is more oriented for use as a debugging
tool.  MPX runtime library usage implies <samp>-lpthread</samp>.  See
also <samp>-static-libmpx</samp>.  The runtime library  behavior can be
influenced using various <code>CHKP_RT_*</code> environment variables.  See
<a href="https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler">https://gcc.gnu.org/wiki/Intel%20MPX%20support%20in%20the%20GCC%20compiler</a>
for more details.
</p>
<p>Generated instrumentation may be controlled by various
<samp>-fchkp-*</samp> options and by the <code>bnd_variable_size</code>
structure field attribute (see <a href="Type-Attributes.html#Type-Attributes">Type Attributes</a>) and
<code>bnd_legacy</code>, and <code>bnd_instrument</code> function attributes
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>).  GCC also provides a number of built-in
functions for controlling the Pointer Bounds Checker.  See <a href="Pointer-Bounds-Checker-builtins.html#Pointer-Bounds-Checker-builtins">Pointer Bounds Checker builtins</a>, for more information.
</p>
</dd>
<dt><code>-fchkp-check-incomplete-type</code></dt>
<dd><a name="index-fchkp_002dcheck_002dincomplete_002dtype"></a>
<a name="index-fno_002dchkp_002dcheck_002dincomplete_002dtype"></a>
<p>Generate pointer bounds checks for variables with incomplete type.
Enabled by default.
</p>
</dd>
<dt><code>-fchkp-narrow-bounds</code></dt>
<dd><a name="index-fchkp_002dnarrow_002dbounds"></a>
<a name="index-fno_002dchkp_002dnarrow_002dbounds"></a>
<p>Controls bounds used by Pointer Bounds Checker for pointers to object
fields.  If narrowing is enabled then field bounds are used.  Otherwise
object bounds are used.  See also <samp>-fchkp-narrow-to-innermost-array</samp>
and <samp>-fchkp-first-field-has-own-bounds</samp>.  Enabled by default.
</p>
</dd>
<dt><code>-fchkp-first-field-has-own-bounds</code></dt>
<dd><a name="index-fchkp_002dfirst_002dfield_002dhas_002down_002dbounds"></a>
<a name="index-fno_002dchkp_002dfirst_002dfield_002dhas_002down_002dbounds"></a>
<p>Forces Pointer Bounds Checker to use narrowed bounds for the address of the
first field in the structure.  By default a pointer to the first field has
the same bounds as a pointer to the whole structure.
</p>
</dd>
<dt><code>-fchkp-narrow-to-innermost-array</code></dt>
<dd><a name="index-fchkp_002dnarrow_002dto_002dinnermost_002darray"></a>
<a name="index-fno_002dchkp_002dnarrow_002dto_002dinnermost_002darray"></a>
<p>Forces Pointer Bounds Checker to use bounds of the innermost arrays in
case of nested static array access.  By default this option is disabled and
bounds of the outermost array are used.
</p>
</dd>
<dt><code>-fchkp-optimize</code></dt>
<dd><a name="index-fchkp_002doptimize"></a>
<a name="index-fno_002dchkp_002doptimize"></a>
<p>Enables Pointer Bounds Checker optimizations.  Enabled by default at
optimization levels <samp>-O</samp>, <samp>-O2</samp>, <samp>-O3</samp>.
</p>
</dd>
<dt><code>-fchkp-use-fast-string-functions</code></dt>
<dd><a name="index-fchkp_002duse_002dfast_002dstring_002dfunctions"></a>
<a name="index-fno_002dchkp_002duse_002dfast_002dstring_002dfunctions"></a>
<p>Enables use of <code>*_nobnd</code> versions of string functions (not copying bounds)
by Pointer Bounds Checker.  Disabled by default.
</p>
</dd>
<dt><code>-fchkp-use-nochk-string-functions</code></dt>
<dd><a name="index-fchkp_002duse_002dnochk_002dstring_002dfunctions"></a>
<a name="index-fno_002dchkp_002duse_002dnochk_002dstring_002dfunctions"></a>
<p>Enables use of <code>*_nochk</code> versions of string functions (not checking bounds)
by Pointer Bounds Checker.  Disabled by default.
</p>
</dd>
<dt><code>-fchkp-use-static-bounds</code></dt>
<dd><a name="index-fchkp_002duse_002dstatic_002dbounds"></a>
<a name="index-fno_002dchkp_002duse_002dstatic_002dbounds"></a>
<p>Allow Pointer Bounds Checker to generate static bounds holding
bounds of static variables.  Enabled by default.
</p>
</dd>
<dt><code>-fchkp-use-static-const-bounds</code></dt>
<dd><a name="index-fchkp_002duse_002dstatic_002dconst_002dbounds"></a>
<a name="index-fno_002dchkp_002duse_002dstatic_002dconst_002dbounds"></a>
<p>Use statically-initialized bounds for constant bounds instead of
generating them each time they are required.  By default enabled when
<samp>-fchkp-use-static-bounds</samp> is enabled.
</p>
</dd>
<dt><code>-fchkp-treat-zero-dynamic-size-as-infinite</code></dt>
<dd><a name="index-fchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite"></a>
<a name="index-fno_002dchkp_002dtreat_002dzero_002ddynamic_002dsize_002das_002dinfinite"></a>
<p>With this option, objects with incomplete type whose
dynamically-obtained size is zero are treated as having infinite size
instead by Pointer Bounds
Checker.  This option may be helpful if a program is linked with a library
missing size information for some symbols.  Disabled by default.
</p>
</dd>
<dt><code>-fchkp-check-read</code></dt>
<dd><a name="index-fchkp_002dcheck_002dread"></a>
<a name="index-fno_002dchkp_002dcheck_002dread"></a>
<p>Instructs Pointer Bounds Checker to generate checks for all read
accesses to memory.  Enabled by default.
</p>
</dd>
<dt><code>-fchkp-check-write</code></dt>
<dd><a name="index-fchkp_002dcheck_002dwrite"></a>
<a name="index-fno_002dchkp_002dcheck_002dwrite"></a>
<p>Instructs Pointer Bounds Checker to generate checks for all write
accesses to memory.  Enabled by default.
</p>
</dd>
<dt><code>-fchkp-store-bounds</code></dt>
<dd><a name="index-fchkp_002dstore_002dbounds"></a>
<a name="index-fno_002dchkp_002dstore_002dbounds"></a>
<p>Instructs Pointer Bounds Checker to generate bounds stores for
pointer writes.  Enabled by default.
</p>
</dd>
<dt><code>-fchkp-instrument-calls</code></dt>
<dd><a name="index-fchkp_002dinstrument_002dcalls"></a>
<a name="index-fno_002dchkp_002dinstrument_002dcalls"></a>
<p>Instructs Pointer Bounds Checker to pass pointer bounds to calls.
Enabled by default.
</p>
</dd>
<dt><code>-fchkp-instrument-marked-only</code></dt>
<dd><a name="index-fchkp_002dinstrument_002dmarked_002donly"></a>
<a name="index-fno_002dchkp_002dinstrument_002dmarked_002donly"></a>
<p>Instructs Pointer Bounds Checker to instrument only functions
marked with the <code>bnd_instrument</code> attribute
(see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>).  Disabled by default.
</p>
</dd>
<dt><code>-fchkp-use-wrappers</code></dt>
<dd><a name="index-fchkp_002duse_002dwrappers"></a>
<a name="index-fno_002dchkp_002duse_002dwrappers"></a>
<p>Allows Pointer Bounds Checker to replace calls to built-in functions
with calls to wrapper functions.  When <samp>-fchkp-use-wrappers</samp>
is used to link a program, the GCC driver automatically links
against <samp>libmpxwrappers</samp>.  See also <samp>-static-libmpxwrappers</samp>.
Enabled by default.
</p>
</dd>
<dt><code>-fstack-protector</code></dt>
<dd><a name="index-fstack_002dprotector"></a>
<p>Emit extra code to check for buffer overflows, such as stack smashing
attacks.  This is done by adding a guard variable to functions with
vulnerable objects.  This includes functions that call <code>alloca</code>, and
functions with buffers larger than 8 bytes.  The guards are initialized
when a function is entered and then checked when the function exits.
If a guard check fails, an error message is printed and the program exits.
</p>
</dd>
<dt><code>-fstack-protector-all</code></dt>
<dd><a name="index-fstack_002dprotector_002dall"></a>
<p>Like <samp>-fstack-protector</samp> except that all functions are protected.
</p>
</dd>
<dt><code>-fstack-protector-strong</code></dt>
<dd><a name="index-fstack_002dprotector_002dstrong"></a>
<p>Like <samp>-fstack-protector</samp> but includes additional functions to
be protected &mdash; those that have local array definitions, or have
references to local frame addresses.
</p>
</dd>
<dt><code>-fstack-protector-explicit</code></dt>
<dd><a name="index-fstack_002dprotector_002dexplicit"></a>
<p>Like <samp>-fstack-protector</samp> but only protects those functions which
have the <code>stack_protect</code> attribute.
</p>
</dd>
<dt><code>-fstack-check</code></dt>
<dd><a name="index-fstack_002dcheck"></a>
<p>Generate code to verify that you do not go beyond the boundary of the
stack.  You should specify this flag if you are running in an
environment with multiple threads, but you only rarely need to specify it in
a single-threaded environment since stack overflow is automatically
detected on nearly all systems if there is only one stack.
</p>
<p>Note that this switch does not actually cause checking to be done; the
operating system or the language runtime must do that.  The switch causes
generation of code to ensure that they see the stack being extended.
</p>
<p>You can additionally specify a string parameter: &lsquo;<samp>no</samp>&rsquo; means no
checking, &lsquo;<samp>generic</samp>&rsquo; means force the use of old-style checking,
&lsquo;<samp>specific</samp>&rsquo; means use the best checking method and is equivalent
to bare <samp>-fstack-check</samp>.
</p>
<p>Old-style checking is a generic mechanism that requires no specific
target support in the compiler but comes with the following drawbacks:
</p>
<ol>
<li> Modified allocation strategy for large objects: they are always
allocated dynamically if their size exceeds a fixed threshold.

</li><li> Fixed limit on the size of the static frame of functions: when it is
topped by a particular function, stack checking is not reliable and
a warning is issued by the compiler.

</li><li> Inefficiency: because of both the modified allocation strategy and the
generic implementation, code performance is hampered.
</li></ol>

<p>Note that old-style stack checking is also the fallback method for
&lsquo;<samp>specific</samp>&rsquo; if no target support has been added in the compiler.
</p>
</dd>
<dt><code>-fstack-limit-register=<var>reg</var></code></dt>
<dt><code>-fstack-limit-symbol=<var>sym</var></code></dt>
<dt><code>-fno-stack-limit</code></dt>
<dd><a name="index-fstack_002dlimit_002dregister"></a>
<a name="index-fstack_002dlimit_002dsymbol"></a>
<a name="index-fno_002dstack_002dlimit"></a>
<p>Generate code to ensure that the stack does not grow beyond a certain value,
either the value of a register or the address of a symbol.  If a larger
stack is required, a signal is raised at run time.  For most targets,
the signal is raised before the stack overruns the boundary, so
it is possible to catch the signal without taking special precautions.
</p>
<p>For instance, if the stack starts at absolute address &lsquo;<samp>0x80000000</samp>&rsquo;
and grows downwards, you can use the flags
<samp>-fstack-limit-symbol=__stack_limit</samp> and
<samp>-Wl,--defsym,__stack_limit=0x7ffe0000</samp> to enforce a stack limit
of 128KB.  Note that this may only work with the GNU linker.
</p>
<p>You can locally override stack limit checking by using the
<code>no_stack_limit</code> function attribute (see <a href="Function-Attributes.html#Function-Attributes">Function Attributes</a>).
</p>
</dd>
<dt><code>-fsplit-stack</code></dt>
<dd><a name="index-fsplit_002dstack"></a>
<p>Generate code to automatically split the stack before it overflows.
The resulting program has a discontiguous stack which can only
overflow if the program is unable to allocate any more memory.  This
is most useful when running threaded programs, as it is no longer
necessary to calculate a good stack size to use for each thread.  This
is currently only implemented for the x86 targets running
GNU/Linux.
</p>
<p>When code compiled with <samp>-fsplit-stack</samp> calls code compiled
without <samp>-fsplit-stack</samp>, there may not be much stack space
available for the latter code to run.  If compiling all code,
including library code, with <samp>-fsplit-stack</samp> is not an option,
then the linker can fix up these calls so that the code compiled
without <samp>-fsplit-stack</samp> always has a large stack.  Support for
this is implemented in the gold linker in GNU binutils release 2.21
and later.
</p>
</dd>
<dt><code>-fvtable-verify=<span class="roman">[</span>std<span class="roman">|</span>preinit<span class="roman">|</span>none<span class="roman">]</span></code></dt>
<dd><a name="index-fvtable_002dverify"></a>
<p>This option is only available when compiling C++ code.
It turns on (or off, if using <samp>-fvtable-verify=none</samp>) the security
feature that verifies at run time, for every virtual call, that
the vtable pointer through which the call is made is valid for the type of
the object, and has not been corrupted or overwritten.  If an invalid vtable
pointer is detected at run time, an error is reported and execution of the
program is immediately halted.
</p>
<p>This option causes run-time data structures to be built at program startup,
which are used for verifying the vtable pointers.  
The options &lsquo;<samp>std</samp>&rsquo; and &lsquo;<samp>preinit</samp>&rsquo;
control the timing of when these data structures are built.  In both cases the
data structures are built before execution reaches <code>main</code>.  Using
<samp>-fvtable-verify=std</samp> causes the data structures to be built after
shared libraries have been loaded and initialized.
<samp>-fvtable-verify=preinit</samp> causes them to be built before shared
libraries have been loaded and initialized.
</p>
<p>If this option appears multiple times in the command line with different
values specified, &lsquo;<samp>none</samp>&rsquo; takes highest priority over both &lsquo;<samp>std</samp>&rsquo; and
&lsquo;<samp>preinit</samp>&rsquo;; &lsquo;<samp>preinit</samp>&rsquo; takes priority over &lsquo;<samp>std</samp>&rsquo;.
</p>
</dd>
<dt><code>-fvtv-debug</code></dt>
<dd><a name="index-fvtv_002ddebug"></a>
<p>When used in conjunction with <samp>-fvtable-verify=std</samp> or 
<samp>-fvtable-verify=preinit</samp>, causes debug versions of the 
runtime functions for the vtable verification feature to be called.  
This flag also causes the compiler to log information about which 
vtable pointers it finds for each class.
This information is written to a file named <samp>vtv_set_ptr_data.log</samp> 
in the directory named by the environment variable <code>VTV_LOGS_DIR</code> 
if that is defined or the current working directory otherwise.
</p>
<p>Note:  This feature <em>appends</em> data to the log file. If you want a fresh log
file, be sure to delete any existing one.
</p>
</dd>
<dt><code>-fvtv-counts</code></dt>
<dd><a name="index-fvtv_002dcounts"></a>
<p>This is a debugging flag.  When used in conjunction with
<samp>-fvtable-verify=std</samp> or <samp>-fvtable-verify=preinit</samp>, this
causes the compiler to keep track of the total number of virtual calls
it encounters and the number of verifications it inserts.  It also
counts the number of calls to certain run-time library functions
that it inserts and logs this information for each compilation unit.
The compiler writes this information to a file named
<samp>vtv_count_data.log</samp> in the directory named by the environment
variable <code>VTV_LOGS_DIR</code> if that is defined or the current working
directory otherwise.  It also counts the size of the vtable pointer sets
for each class, and writes this information to <samp>vtv_class_set_sizes.log</samp>
in the same directory.
</p>
<p>Note:  This feature <em>appends</em> data to the log files.  To get fresh log
files, be sure to delete any existing ones.
</p>
</dd>
<dt><code>-finstrument-functions</code></dt>
<dd><a name="index-finstrument_002dfunctions"></a>
<p>Generate instrumentation calls for entry and exit to functions.  Just
after function entry and just before function exit, the following
profiling functions are called with the address of the current
function and its call site.  (On some platforms,
<code>__builtin_return_address</code> does not work beyond the current
function, so the call site information may not be available to the
profiling functions otherwise.)
</p>
<div class="smallexample">
<pre class="smallexample">void __cyg_profile_func_enter (void *this_fn,
                               void *call_site);
void __cyg_profile_func_exit  (void *this_fn,
                               void *call_site);
</pre></div>

<p>The first argument is the address of the start of the current function,
which may be looked up exactly in the symbol table.
</p>
<p>This instrumentation is also done for functions expanded inline in other
functions.  The profiling calls indicate where, conceptually, the
inline function is entered and exited.  This means that addressable
versions of such functions must be available.  If all your uses of a
function are expanded inline, this may mean an additional expansion of
code size.  If you use <code>extern inline</code> in your C code, an
addressable version of such functions must be provided.  (This is
normally the case anyway, but if you get lucky and the optimizer always
expands the functions inline, you might have gotten away without
providing static copies.)
</p>
<p>A function may be given the attribute <code>no_instrument_function</code>, in
which case this instrumentation is not done.  This can be used, for
example, for the profiling functions listed above, high-priority
interrupt routines, and any functions from which the profiling functions
cannot safely be called (perhaps signal handlers, if the profiling
routines generate output or allocate memory).
</p>
</dd>
<dt><code>-finstrument-functions-exclude-file-list=<var>file</var>,<var>file</var>,&hellip;</code></dt>
<dd><a name="index-finstrument_002dfunctions_002dexclude_002dfile_002dlist"></a>

<p>Set the list of functions that are excluded from instrumentation (see
the description of <samp>-finstrument-functions</samp>).  If the file that
contains a function definition matches with one of <var>file</var>, then
that function is not instrumented.  The match is done on substrings:
if the <var>file</var> parameter is a substring of the file name, it is
considered to be a match.
</p>
<p>For example:
</p>
<div class="smallexample">
<pre class="smallexample">-finstrument-functions-exclude-file-list=/bits/stl,include/sys
</pre></div>

<p>excludes any inline function defined in files whose pathnames
contain <samp>/bits/stl</samp> or <samp>include/sys</samp>.
</p>
<p>If, for some reason, you want to include letter &lsquo;<samp>,</samp>&rsquo; in one of
<var>sym</var>, write &lsquo;<samp>\,</samp>&rsquo;. For example,
<samp>-finstrument-functions-exclude-file-list='\,\,tmp'</samp>
(note the single quote surrounding the option).
</p>
</dd>
<dt><code>-finstrument-functions-exclude-function-list=<var>sym</var>,<var>sym</var>,&hellip;</code></dt>
<dd><a name="index-finstrument_002dfunctions_002dexclude_002dfunction_002dlist"></a>

<p>This is similar to <samp>-finstrument-functions-exclude-file-list</samp>,
but this option sets the list of function names to be excluded from
instrumentation.  The function name to be matched is its user-visible
name, such as <code>vector&lt;int&gt; blah(const vector&lt;int&gt; &amp;)</code>, not the
internal mangled name (e.g., <code>_Z4blahRSt6vectorIiSaIiEE</code>).  The
match is done on substrings: if the <var>sym</var> parameter is a substring
of the function name, it is considered to be a match.  For C99 and C++
extended identifiers, the function name must be given in UTF-8, not
using universal character names.
</p>
</dd>
</dl>


<hr>
<div class="header">
<p>
Next: <a href="Preprocessor-Options.html#Preprocessor-Options" accesskey="n" rel="next">Preprocessor Options</a>, Previous: <a href="Optimize-Options.html#Optimize-Options" accesskey="p" rel="prev">Optimize Options</a>, Up: <a href="Invoking-GCC.html#Invoking-GCC" accesskey="u" rel="up">Invoking GCC</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
